home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / icon.doc < prev    next >
Encoding:
Text File  |  1999-10-22  |  62.4 KB  |  1,803 lines
  1. TABLE OF CONTENTS
  2.  
  3. icon.library/AddFreeList
  4. icon.library/BumpRevision
  5. icon.library/ChangeToSelectedIconColor
  6. icon.library/DeleteDiskObject
  7. icon.library/DrawIconStateA
  8. icon.library/DupDiskObjectA
  9. icon.library/FindToolType
  10. icon.library/FreeDiskObject
  11. icon.library/FreeFreeList
  12. icon.library/GetDefDiskObject
  13. icon.library/GetDiskObject
  14. icon.library/GetDiskObjectNew
  15. icon.library/GetIconRectangleA
  16. icon.library/GetIconTagList
  17. icon.library/IconControlA
  18. icon.library/LayoutIconA
  19. icon.library/MatchToolValue
  20. icon.library/NewDiskObject
  21. icon.library/PutDefDiskObject
  22. icon.library/PutDiskObject
  23. icon.library/PutIconTagList
  24. icon.library/AddFreeList                             icon.library/AddFreeList
  25.  
  26.    NAME
  27.     AddFreeList - add memory to a free list.
  28.  
  29.    SYNOPSIS
  30.     status = AddFreeList(free, mem, len)
  31.       D0                  A0    A1   A2
  32.  
  33.     BOOL AddFreeList(struct FreeList *, APTR, ULONG);
  34.  
  35.    FUNCTION
  36.     This routine adds the specified memory to the free list.
  37.     The free list will be extended (if required).  If there
  38.     is not enough memory to complete the call, NULL is returned.
  39.  
  40.     Note that AddFreeList() does NOT allocate the requested memory.
  41.     It only records the memory in the free list.
  42.  
  43.    INPUTS
  44.     free -- a pointer to a FreeList structure
  45.     mem -- the base of the memory to be recorded
  46.     len -- the length of the memory to be recorded
  47.  
  48.    RESULTS
  49.     status -- TRUE if the call succeeded else FALSE;
  50.  
  51.    SEE ALSO
  52.     exec.library/AllocEntry
  53.     exec.library/FreeEntry
  54.     icon.library/FreeFreeList
  55.     workbench/workbench.h
  56.  
  57. icon.library/BumpRevision                           icon.library/BumpRevision
  58.  
  59.    NAME
  60.     BumpRevision - reformat a name for a second copy.
  61.  
  62.    SYNOPSIS
  63.     result = BumpRevision(newbuf, oldname)
  64.       D0                    A0      A1
  65.  
  66.     STRPTR BumpRevision(STRPTR, STRPTR);
  67.  
  68.    FUNCTION
  69.     BumpRevision takes a name and turns it into a "copy_of_name".
  70.     It knows how to deal with copies of copies.  The routine
  71.     will truncate the new name to the maximum dos name size
  72.     (currently 30 characters).
  73.  
  74.    INPUTS
  75.     newbuf - the new buffer that will receive the name
  76.              (it must be at least 31 characters long).
  77.     oldname - the original name
  78.  
  79.    RESULTS
  80.     result - a pointer to newbuf
  81.  
  82.    EXAMPLE
  83.     oldname                          newbuf
  84.     -------                          ------
  85.     "foo"                            "copy_of_foo"
  86.     "copy_of_foo"                    "copy_2_of_foo"
  87.     "copy_2_of_foo"                  "copy_3_of_foo"
  88.     "copy_199_of_foo"                "copy_200_of_foo"
  89.     "copy foo"                       "copy_of_copy foo"
  90.     "copy_0_of_foo"                  "copy_1_of_foo"
  91.     "012345678901234567890123456789" "copy_of_0123456789012345678901"
  92.  
  93. icon.library/ChangeToSelectedIconColor icon.library/ChangeToSelectedIconColor
  94.  
  95.    NAME
  96.     ChangeToSelectedIconColor -- Modify an RGB colour value for use in
  97.         a selected icon image (V44)
  98.  
  99.    SYNOPSIS
  100.     ChangeToSelectedIconColor(cr)
  101.                               A0
  102.  
  103.     VOID ChangeToSelectedIconColor(struct ColorRegister *cr);
  104.  
  105.    FUNCTION
  106.     This function will change the provided RGB colour value to make it
  107.     suitable for use in an icon's select image. This may involve darkening
  108.     or toning the colour. Usually, icon.library calls this function
  109.     when creating a select image for palette mapped icons which do not
  110.     contain "real" select images.
  111.  
  112.    INPUTS
  113.     cr -- Pointer to a ColorRegister, containing the RGB colour value
  114.         to be changed.
  115.  
  116. icon.library/DeleteDiskObject                   icon.library/DeleteDiskObject
  117.  
  118.    NAME
  119.     DeleteDiskObject - Delete a Workbench disk object from disk.     (V37)
  120.  
  121.    SYNOPSIS
  122.     result = DeleteDiskObject(name)
  123.       D0                      A0
  124.  
  125.     BOOL DeleteDiskObject(STRPTR);
  126.  
  127.    FUNCTION
  128.     This routine will try to delete a Workbench disk object from disk.
  129.     The name parameter will have ".info" postpended to it, and the
  130.     icon file of that name will be deleted.  If the call fails,
  131.     it will return FALSE. The reason for the failure may be obtained
  132.     via dos.library/IoErr().
  133.  
  134.     This call also updates the Workbench screen if needed.
  135.  
  136.     Using this routine protects you from any future changes to
  137.     the way icons are stored within the system.
  138.  
  139.    INPUTS
  140.     name -- name of the object (char *)
  141.  
  142.    RESULTS
  143.     result -- TRUE if it worked, FALSE if not.
  144.  
  145.    EXAMPLE
  146.  
  147.     error = 0;
  148.  
  149.     /* Check if you have the right library version */
  150.     if(IconBase->lib_Version > 36)
  151.     {
  152.         if (!DeleteDiskObject(name))
  153.             error = IoErr();
  154.     }
  155.     else
  156.     {
  157.         /* Delete name plus ".info" */
  158.     }
  159.  
  160.     if (error != 0)
  161.     {
  162.         /* Do error routine...*/
  163.     }
  164.  
  165.    SEE ALSO
  166.     dos.library/IoErr
  167.     icon.library/PutDiskObject
  168.     icon.library/GetDiskObject
  169.     icon.library/FreeDiskObject
  170.     icon.library/GetIconTagList
  171.     icon.library/PutIconTagList
  172.  
  173. icon.library/DrawIconStateA                       icon.library/DrawIconStateA
  174.  
  175.    NAME
  176.     DrawIconStateA -- Draw an icon as if it were an image (V44)
  177.  
  178.    SYNOPSIS
  179.     DrawIconStateA(rp,icon,label,leftEdge,topEdge,state,tags)
  180.                    A0 A1   A2    D0       D1      D2    A3
  181.  
  182.     VOID DrawIconStateA(struct RastPort *rp,struct DiskObject *icon,
  183.                         STRPTR label,LONG leftEdge,LONG topEdge,
  184.                         ULONG state,struct TagItem *tags);
  185.  
  186.     DrawIconState(rp,icon,label,leftEdge,topEdge,state,...);
  187.  
  188.     VOID DrawIconState(struct RastPort *rp,struct DiskObject *icon,
  189.                        STRPTR label,LONG leftEdge,LONG topEdge,
  190.                        ULONG state,...);
  191.  
  192.    FUNCTION
  193.     This function will draw an icon as if it were an image; if
  194.     a label is provided, it will be printed below it.
  195.  
  196.    INPUTS
  197.     rp -- Pointer to the RastPort to draw into; the RastPort clipping
  198.         rules, font, style, text colours and drawing mode will be used.
  199.     icon -- Pointer to a struct DiskObject.
  200.     label -- Pointer to a NUL-terminated string, or NULL if
  201.         no label text is to be printed.
  202.     leftEdge, topEdge -- Coordinates at which the icon image
  203.         should be drawn, including its border; please note that the
  204.         icon label may extend in whole or in part beyond the
  205.         leftEdge you have specified.
  206.     state -- Select how and which icon image should be drawn;
  207.         see intuition/imageclass.h for supported states.
  208.     tags -- Additional drawing options
  209.  
  210.    TAGS
  211.     ICONDRAWA_DrawInfo (struct DrawInfo *) -- Drawing information data
  212.         associated with the RastPort to draw into. The DrawInfo
  213.         contents affect the colours of the border drawn around the
  214.         icon image and also carry display aspect ratio information.
  215.         If this tag is NULL, the default rendering pens for the
  216.         screen selected via IconControl(...,ICONA_SetGlobalScreen,...)
  217.         will be used instead.
  218.  
  219.         This tag defaults to NULL.
  220.  
  221.     ICONDRAWA_Frameless (BOOL) -- Draw the icon without the
  222.         surrounding border.
  223.  
  224.         This tag defaults to FALSE.
  225.  
  226.     ICONDRAWA_Borderless (BOOL) -- Draw the icon without the
  227.         surrounding border and frame.
  228.  
  229.         This tag defaults to FALSE.
  230.  
  231.     ICONDRAWA_EraseBackground (BOOL) -- When drawing a frameless
  232.         icon, erase the icon background before drawing the icon.
  233.  
  234.         This tag defaults to TRUE.
  235.  
  236.    EXAMPLE
  237.     /* Draw the icon in its normal state, without
  238.      * a label but including a frame.
  239.      */
  240.     struct RastPort *rp;
  241.     struct DiskObject *icon;
  242.  
  243.     DrawIconStateA(rp,icon,NULL,0,0,IDS_NORMAL,NULL);
  244.  
  245.     /* The same again, but without a frame. */
  246.     DrawIconState(rp,icon,NULL,0,0,IDS_NORMAL,
  247.         ICONDRAWA_Frameless,TRUE,
  248.     TAG_DONE);
  249.  
  250.     /* Draw the icon in selected state with a border; the
  251.      * frame colours come from the given DrawInfo.
  252.      */
  253.     struct DrawInfo *drawInfo;
  254.  
  255.     DrawIconState(rp,icon,NULL,0,0,IDS_SELECTED,
  256.         ICONDRAWA_DrawInfo,drawInfo,
  257.     TAG_DONE);
  258.  
  259.    SEE ALSO
  260.     workbench/icon.h
  261.     workbench/workbench.h
  262.     intuition/imageclass.h
  263.     intuition/screens.h
  264.     intuition.library/DrawImageState
  265.     icon.library/GetIconRectangleA
  266.     icon.library/IconControlA
  267.  
  268. icon.library/DupDiskObjectA                       icon.library/DupDiskObjectA
  269.  
  270.    NAME
  271.     DupDiskObjectA -- Duplicate an icon (V44)
  272.  
  273.    SYNOPSIS
  274.     icon = DupDiskObjectA(icon,tags);
  275.     D0                    A0   A1
  276.  
  277.     struct DiskObject * DupDiskObjectA(struct DiskObject *icon,
  278.                                        struct TagItem *tags);
  279.  
  280.     icon = DupDiskObject(icon,tag1,...);
  281.  
  282.     struct DiskObject * DupDiskObject(struct DiskObject *icon,
  283.                                       Tag tag1,...);
  284.  
  285.    FUNCTION
  286.     This function is used to create a duplicate of a DiskObject
  287.     in memory. It can also be used to create an extended
  288.     ("native") DiskObject data structure from an existing,
  289.     traditional format DiskObject data structure.
  290.  
  291.    INPUTS
  292.     icon -- Pointer to the icon to be duplicated.
  293.     tags -- Control options.
  294.  
  295.    TAGS
  296.     ICONDUPA_DuplicateDrawerData (BOOL) -- Duplicate the DrawerData,
  297.         if available.
  298.  
  299.         This tag defaults to TRUE.
  300.  
  301.     ICONDUPA_DuplicateImages (BOOL) -- Duplicate the icon images;
  302.         note that this DOES NOT include the associated image
  303.         data. To get the image data duplicated, too, also use
  304.         the ICONDUPA_DuplicateImageData tag.
  305.  
  306.         This tag defaults to TRUE.
  307.  
  308.     ICONDUPA_DuplicateImageData (BOOL) -- Duplicate the icon image
  309.         data; this tag works together with the ICONDUPA_DuplicateImages
  310.         tag. If ICONDUPA_DuplicateImageData is set to TRUE, you must
  311.         also set ICONDUPA_DuplicateImages to TRUE.
  312.  
  313.         This tag defaults to TRUE.
  314.  
  315.     ICONDUPA_DuplicateDefaultTool (BOOL) -- Duplicate the icon default
  316.         tool, if available.
  317.  
  318.         This tag defaults to TRUE.
  319.  
  320.     ICONDUPA_DuplicateToolTypes (BOOL) -- Duplicate the icon tool
  321.         types, if available.
  322.  
  323.         This tag defaults to TRUE.
  324.  
  325.     ICONDUPA_DuplicateToolWindow (BOOL) -- Duplicate the icon tool
  326.         window if available.
  327.  
  328.         This tag defaults to TRUE.
  329.  
  330.     ICONDUPA_ActivateImageData (BOOL) -- If the source icon contains
  331.         palette mapped image data that was never put to use (this
  332.         happens if it is retrieved with the GetDiskObject() call rather
  333.         than the new GetIconTagList() call), this tag will cause the
  334.         image data to be analyzed and an attempt to be made to use that
  335.         image data in the duplicate. The resulting icon will be remapped
  336.         for display on the default screen, such as the Workbench screen.
  337.  
  338.         This tag defaults to FALSE.
  339.  
  340.     ICONA_ErrorCode (LONG *) -- Pointer to a LONG word variable to
  341.         store error codes in. Note that this variable will be
  342.         initialized regardless of whether an error occured or not.
  343.         Thus, you can check for an error condition by comparing the
  344.         variable contents against 0; 0 indicates success, all other
  345.         values are error codes as defined by dos.library.
  346.  
  347.    RESULT
  348.     icon -- Pointer to a struct DiskObject or NULL in case of error.
  349.         You can use IoErr() to retrieve the error code or use the
  350.         ICONA_ErrorCode tag instead.
  351.  
  352.    NOTES
  353.     Any data you chose not to have duplicated will be set to NULL.
  354.     For example, if you specified "ICONDUPA_DuplicateImages,FALSE",
  355.     then the resulting icon's do_Gadget.GadgetRender and
  356.     do_Gadget.SelectRender will both be NULL.
  357.  
  358.    SEE ALSO
  359.     dos.library/IoErr
  360.     workbench/icon.h
  361.     workbench/workbench.h
  362.  
  363. icon.library/FindToolType                           icon.library/FindToolType
  364.  
  365.    NAME
  366.     FindToolType - find the value of a ToolType variable.
  367.  
  368.    SYNOPSIS
  369.     value = FindToolType(toolTypeArray, typeName)
  370.       D0                      A0           A1
  371.  
  372.     STRPTR FindToolType(STRPTR *, STRPTR);
  373.  
  374.    FUNCTION
  375.     This function searches a tool type array for a given entry,
  376.     and returns a pointer to that entry.  This is useful for
  377.     finding standard tool type variables.  The returned
  378.     value is not a new copy of the string but is only
  379.     a pointer to the part of the string after typeName.
  380.  
  381.    INPUTS
  382.     toolTypeArray -- an array of strings (STRPTR *).
  383.     typeName -- the name of the tooltype entry (STRPTR).
  384.  
  385.    RESULTS
  386.     value -- a pointer to a string that is the value bound to typeName,
  387.             or NULL if typeName is not in the toolTypeArray.
  388.  
  389.    EXAMPLE
  390.     Assume the tool type array has two strings in it:
  391.         "FILETYPE=text"
  392.         "TEMPDIR=:t"
  393.  
  394.     FindToolType( toolTypeArray, "FILETYPE" ) returns "text"
  395.     FindToolType( toolTypeArray, "filetype" ) returns "text"
  396.     FindToolType( toolTypeArray, "TEMPDIR" )  returns ":t"
  397.     FindToolType( toolTypeArray, "MAXSIZE" )  returns NULL
  398.     FindToolType( toolTypeArray, "text" )     returns NULL
  399.     FindToolType( toolTypeArray, ":t" )       returns NULL
  400.  
  401.    NOTES
  402.     icon.library V44 tolerates tool type strings with additional
  403.     blanks around the '=' character, such as in "FILETYPE = text".
  404.     Older icon.library versions did not support this.
  405.  
  406.    SEE ALSO
  407.     icon.library/MatchToolValue
  408.  
  409. icon.library/FreeDiskObject                       icon.library/FreeDiskObject
  410.  
  411.    NAME
  412.     FreeDiskObject - free all memory in a Workbench disk object.
  413.  
  414.    SYNOPSIS
  415.     FreeDiskObject(diskobj)
  416.                    A0
  417.  
  418.     void FreeDiskObject(struct DiskObject *);
  419.  
  420.    FUNCTION
  421.     This routine frees all memory in a Workbench disk object, and the
  422.     object itself.  It is implemented via FreeFreeList().
  423.  
  424.     GetDiskObject() takes care of all the initialization required
  425.     to set up the object's free list.  This procedure may ONLY
  426.     be called on a DiskObject allocated via GetDiskObject().
  427.  
  428.    INPUTS
  429.     diskobj -- a pointer to a DiskObject structure; as of V44,
  430.         a NULL diskobj pointer will be ignored.
  431.  
  432.    SEE ALSO
  433.     icon.library/GetDiskObject
  434.     icon.library/PutDiskObject
  435.     icon.library/DeleteDiskObject
  436.     icon.library/FreeFreeList
  437.     icon.library/GetIconTagList
  438.     icon.library/PutIconTagList
  439.  
  440. icon.library/FreeFreeList                           icon.library/FreeFreeList
  441.  
  442.    NAME
  443.     FreeFreeList - free all memory in a free list.
  444.  
  445.    SYNOPSIS
  446.     FreeFreeList(free)
  447.                  A0
  448.  
  449.     void FreeFreeList(struct FreeList *);
  450.  
  451.    FUNCTION
  452.     This routine frees all memory in a free list, and the
  453.     free list itself.  It is useful for easily getting
  454.     rid of all memory in a series of structures.  There is
  455.     a free list in a Workbench object, and this contains
  456.     all the memory associated with that object.
  457.  
  458.     A FreeList is a list of MemList structures.  See the
  459.     MemList and MemEntry documentation for more information.
  460.  
  461.     If the FreeList itself is in the free list, it must be
  462.     in the first MemList in the FreeList.
  463.  
  464.    INPUTS
  465.     free -- a pointer to a FreeList structure; as of V44
  466.         a NULL free parameter will be ignored.
  467.  
  468.    SEE ALSO
  469.     exec.library/AllocEntry
  470.     exec.library/FreeEntry
  471.     icon.library/AddFreeList
  472.     workbench/workbench.h
  473.  
  474. icon.library/GetDefDiskObject                   icon.library/GetDefDiskObject
  475.  
  476.    NAME
  477.     GetDefDiskObject - read default wb disk object from disk.       (V36)
  478.  
  479.    SYNOPSIS
  480.     diskobj = GetDefDiskObject(def_type)
  481.       D0                          D0
  482.  
  483.     struct DiskObject *GetDefDiskObject(LONG);
  484.  
  485.    FUNCTION
  486.     This routine reads in a default Workbench disk object from disk.
  487.     The valid def_types can be found in workbench/workbench.h and
  488.     currently include WBDISK thru WBKICK. If the call fails,
  489.     it will return NULL. The reason for the failure may be obtained
  490.     via IoErr().
  491.  
  492.     Using this routine protects you from any future changes to
  493.     the way default icons are stored within the system.
  494.  
  495.    INPUTS
  496.     def_type -- default icon type (WBDISK thru WBKICK).
  497.  
  498.    RESULTS
  499.     diskobj -- the default Workbench disk object in question
  500.  
  501.    NOTES
  502.     icon.library V36 through V40 did not support the WBDEVICE default
  503.     icon type.
  504.  
  505.    SEE ALSO
  506.     dos.library/IoErr
  507.     icon.library/PutDefDiskObject
  508.     icon.library/PutIconTagList
  509.  
  510. icon.library/GetDiskObject                         icon.library/GetDiskObject
  511.  
  512.    NAME
  513.     GetDiskObject - read in a Workbench disk object from disk.
  514.  
  515.    SYNOPSIS
  516.     diskobj = GetDiskObject(name)
  517.       D0                      A0
  518.  
  519.     struct DiskObject *GetDiskObject(STRPTR);
  520.  
  521.    FUNCTION
  522.     This routine reads in a Workbench disk object in from disk.  The
  523.     name parameter will have ".info" postpended to it, and the
  524.     icon file of that name will be read.  If the call fails,
  525.     it will return NULL.  The reason for the failure may be obtained
  526.     via IoErr().
  527.  
  528.     Using this routine protects you from any future changes to
  529.     the way icons are stored within the system.
  530.  
  531.     A FreeList structure is allocated just after the DiskObject
  532.     structure; FreeDiskObject makes use of this to get rid of the
  533.     memory that was allocated.
  534.  
  535.    INPUTS
  536.     name -- name of the object (STRPTR) or NULL if you just want a
  537.             DiskObject structure allocated for you (useful when
  538.             calling AddAppIcon() in workbench.library).
  539.  
  540.    RESULTS
  541.     diskobj -- the Workbench disk object in question
  542.  
  543.    SEE ALSO
  544.     dos.library/IoErr
  545.     icon.library/DeleteDiskObject
  546.     icon.library/FreeDiskObject
  547.     icon.library/GetDiskObjectNew
  548.     icon.library/GetIconTagList
  549.     icon.library/NewDiskObject
  550.     icon.library/PutDiskObject
  551.     icon.library/PutIconTagList
  552.     workbench.library/AddAppIconA
  553.  
  554. icon.library/GetDiskObjectNew                   icon.library/GetDiskObjectNew
  555.  
  556.    NAME
  557.     GetDiskObjectNew - read in a Workbench disk object from disk.    (V36)
  558.  
  559.    SYNOPSIS
  560.     diskobj = GetDiskObjectNew(name)
  561.       D0                      A0
  562.  
  563.     struct DiskObject *GetDiskObjectNew(STRPTR);
  564.  
  565.    FUNCTION
  566.     This routine reads in a Workbench disk object in from disk.  The
  567.     name parameter will have ".info" postpended to it, and the
  568.     icon file of that name will be read.  If the call fails,
  569.     it will return zero.  The reason for the failure may be obtained
  570.     via IoErr().
  571.  
  572.     Using this routine protects you from any future changes to
  573.     the way icons are stored within the system.
  574.  
  575.     A FreeList structure is allocated just after the DiskObject
  576.     structure; FreeDiskObject makes use of this to get rid of the
  577.     memory that was allocated.
  578.  
  579.     This call is functionally identical to GetDiskObject() with one
  580.     exception. If its call to GetDiskObject() fails, this function calls
  581.     GetDefDiskObject(). This is useful when there is no .info file for the
  582.     icon you are trying to get a disk object for. Applications that use
  583.     workbench application windows MUST use this call if they want to handle
  584.     the user dropping an icon (that doesn't have a ".info" file) on their
  585.     window. The V2.0 icon editor program is an example of a Workbench
  586.     application window that uses this call.
  587.  
  588.    INPUTS
  589.     name -- name of the object (STRPTR) or NULL if you just want a
  590.             DiskObject structure allocated for you (useful when
  591.             calling AddAppIcon() in workbench.library).
  592.  
  593.    RESULTS
  594.     diskobj -- the Workbench disk object in question
  595.  
  596.    SEE ALSO
  597.     dos.library/IoErr
  598.     icon.library/FreeDiskObject
  599.     icon.library/GetDiskObject
  600.     icon.library/PutDiskObject
  601.     icon.library/DeleteDiskObject
  602.     icon.library/GetIconTagList
  603.     icon.library/PutIconTagList
  604.     workbench.library/AddAppIconA
  605.  
  606. icon.library/GetIconRectangleA                 icon.library/GetIconRectangleA
  607.  
  608.    NAME
  609.     GetIconRectangleA -- Query the size of the area an icon renders into (V44)
  610.  
  611.    SYNOPSIS
  612.     success = GetIconRectangleA(rp,icon,label,rectangle,tags)
  613.     D0                          A0 A1   A2    A3        A4
  614.  
  615.     BOOL GetIconRectangleA(struct RastPort *rp,struct DiskObject *icon,
  616.                            STRPTR label,struct Rectangle *rectangle,
  617.                            struct TagItem *tags);
  618.  
  619.     success = GetIconRectangle(rp,icon,label,rectangle,...);
  620.  
  621.     BOOL GetIconRectangle(struct RastPort *rp,struct DiskObject *icon,
  622.                           STRPTR label,struct Rectangle *rectangle,...);
  623.  
  624.    FUNCTION
  625.     This function will calculate the size of the area icon rendering
  626.     would affect.
  627.  
  628.    INPUTS
  629.     rp -- Pointer to the RastPort to use for calculating the
  630.         the size of the label with respect to the font and
  631.         style options currently in use; this parameter may be
  632.         NULL if the label is NULL, too.
  633.     icon -- Pointer to a struct DiskObject.
  634.     label -- Pointer to a NUL-terminated string, or NULL if
  635.         no label text is to enter the calculation.
  636.     rectangle -- Pointer to a struct Rectangle to fill in. The
  637.         contents will take the size of the icon image, the icon
  638.         border size and -- if you provide RastPort and label
  639.         text -- the icon label into account. Due to how labels
  640.         are printed, the rectangle->MinX and rectangle->MinY
  641.         members may be negative.
  642.     tags -- Additional drawing options to be taken into account.
  643.  
  644.    TAGS
  645.     ICONDRAWA_DrawInfo (struct DrawInfo *) -- Drawing information data
  646.         associated with the RastPort parameter passed in.
  647.  
  648.         This tag defaults to NULL.
  649.  
  650.     ICONDRAWA_Borderless (BOOL) -- When calculating the size of
  651.         the rectangle, this tag allows you to leave the icon
  652.         border size out of the equation.
  653.  
  654.         This tag defaults to FALSE.
  655.  
  656.    RESULTS
  657.     success -- TRUE if the parameters were well-formed and
  658.         the output data fits into the Rectangle data
  659.         structure (which may not be the case if the image
  660.         is too large for a signed 16 bit integer to hold).
  661.  
  662.    EXAMPLE
  663.     /* Find out how large an icon is. */
  664.     struct DiskObject *icon;
  665.     struct Rectangle rect;
  666.  
  667.     if(GetIconRectangleA(NULL,NULL,icon,NULL,&rect,NULL))
  668.     {
  669.         LONG width,height;
  670.  
  671.         width = rect.MaxX - rect.MinX + 1;
  672.         height = rect.MaxY - rect.MinY + 1;
  673.  
  674.         Printf("icon is %ld×%ld pixels in size.\n",
  675.             width,height);
  676.     }
  677.  
  678.     /* Find out which area the icon rendering would
  679.      * cover if a label would be printed below it.
  680.      */
  681.     struct RastPort *rp;
  682.  
  683.     if(GetIconRectangle(rp,NULL,icon,"a rather long label text",&rect,TAG_DONE))
  684.     {
  685.         Printf("icon plus label would cover the area %ld,%ld×%ld,%ld\n",
  686.             rect.MinX,rect.MinY,rect.MaxX,rect.MaxY);
  687.     }
  688.  
  689.    NOTES
  690.     This function can be used to optimize on-screen rendering by
  691.     precalculating the area rendering would cover. To make sure that
  692.     the precalculated area size matches the one covered by the actual
  693.     drawing operation, the RastPorts you use for measuring and for
  694.     drawing should share the same font and the same text styles.
  695.  
  696.     The image size calculated by this function can be
  697.     slightly larger than the data you will find in the icon's
  698.     do_Gadget.GadgetRender Image structure since the icon border
  699.     will be taken into account. This happens regardless of whether
  700.     icon.library was switched into frameless icon rendering mode
  701.     or whether the icon is frameless. To obtain the size of the
  702.     icon without taking the border into account, use the
  703.     ICONDRAWA_Borderless tag.
  704.  
  705.    SEE ALSO
  706.     workbench/icon.h
  707.     workbench/workbench.h
  708.     icon.library/DrawIconState
  709.     icon.library/IconControlA
  710.  
  711. icon.library/GetIconTagList                       icon.library/GetIconTagList
  712.  
  713.    NAME
  714.     GetIconTagList -- Retrieve an icon (V44)
  715.  
  716.    SYNOPSIS
  717.     icon = GetIconTagList(name,tags);
  718.     D0                    A0   A1
  719.  
  720.     struct DiskObject * GetIconTagList(STRPTR name,struct TagItem *tags);
  721.  
  722.     icon = GetIconTags(name,tag1,...);
  723.  
  724.     struct DiskObject * GetIconTags(STRPTR name,Tag tag1,...);
  725.  
  726.    FUNCTION
  727.  
  728.     This function is used to retrieve an icon; the icon can
  729.     belong to a file/drawer/volume or it can be a default icon.
  730.  
  731.    INPUTS
  732.     name -- Name of the object an icon is to be retrieved for,
  733.         or NULL if a default icon is to be retrieved.
  734.     tags -- Retrieval options.
  735.  
  736.    TAGS
  737.     ICONGETA_GetDefaultType (LONG) -- Type of the default icon
  738.         to retrieve; must be one of WBDISK, WBDRAWER, WBTOOL,
  739.         WBPROJECT, WBGARBAGE, WBDEVICE or WBKICK.
  740.  
  741.         If this tag is used, the "name" parameter will be ignored.
  742.  
  743.     ICONGETA_GetDefaultName (STRPTR) -- Name of the default object
  744.         type to retrieve a default icon for. If the named default
  745.         icon cannot be found, NULL will be returned. To avoid
  746.         this, also specify ICONGETA_GetDefaultType: this will provide
  747.         a fall-back and return a "default" default icon instead.
  748.  
  749.         If this tag is used, the "name" parameter will be ignored.
  750.  
  751.     ICONGETA_FailIfUnavailable (BOOL) -- If there is no icon for
  752.         the specified object, this tag will control how to
  753.         proceed: if ICONGETA_FailIfUnavailable is set to TRUE,
  754.         NULL and an error code will be returned; if set to FALSE,
  755.         icon.library will first invoke the global identification
  756.         hook (see icon.library/IconControlA) and then, if necessary,
  757.         provide a default icon for the object in question.
  758.  
  759.         This tag defaults to TRUE.
  760.  
  761.     ICONGETA_GetPaletteMappedIcon (BOOL) -- By default, icon.library
  762.         will try to retrieve the palette mapped version of an icon. To
  763.         change this, set the ICONGETA_GetPaletteMappedIcon tag to FALSE.
  764.  
  765.         This tag defaults to TRUE.
  766.  
  767.     ICONGETA_RemapIcon (BOOL) -- Palette mapped icons will usually
  768.         be automatically remapped for display on the screen
  769.         selected using IconControlA(). If you do not want this to
  770.         happen because, for example, you want to use LayoutIcon()
  771.         instead, you can set the ICONGETA_RemapIcon tag to FALSE.
  772.         Take care when doing this as the icon returned to you
  773.         will have NULL pointers in the do_Gadget.GadgetRender
  774.         and do_Gadget.SelectRender members.
  775.  
  776.         This tag defaults to TRUE.
  777.  
  778.     ICONGETA_IsDefaultIcon (LONG *) -- When retrieving an icon with
  779.         the ICONGETA_FailIfUnavailable tag set to FALSE, you may
  780.         receive a default icon because there is no on-disk icon
  781.         file for the object you wanted to retrieve it for. This
  782.         type of default icon is also known as a "fake" icon.
  783.         To find out whether you have received a fake icon, use the
  784.         ICONGETA_IsDefaultIcon tag.
  785.  
  786.     ICONGETA_GenerateImageMasks (BOOL) -- When loading icons with
  787.         transparent colours or backfill imagery, bit plane masks
  788.         will be generated for later use with DrawIconStateA().
  789.         If you do not need these masks, set this tag to FALSE.
  790.  
  791.         This tag defaults to TRUE.
  792.  
  793.     ICONGETA_Screen (struct Screen *) -- Pointer to the screen
  794.         to remap the icon to; if set to NULL, this keeps the
  795.         icon from getting remapped in the first place (see
  796.         ICONGETA_RemapIcon for the consequences).
  797.  
  798.         This tag defaults to the default screen to remap to, as
  799.         preset by IconControlA().
  800.  
  801.     ICONGETA_Label (STRPTR) -- The label text to be printed below
  802.         the icon when it is put to use lateron. This parameter
  803.         can be useful to figure out the type of the icon to
  804.         be retrieved by the identification hook. For example,
  805.         Workbench may label unreadable disk icons as "DF0:????".
  806.         The identification hook could key on this and supply an
  807.         appropriate icon for the disk.
  808.  
  809.         This tag defaults to NULL.
  810.  
  811.     ICONA_ErrorCode (LONG *) -- Pointer to a LONG word variable to
  812.         store error codes in. Note that this variable will be
  813.         initialized regardless of whether an error occured or not.
  814.         Thus, you can check for an error condition by comparing the
  815.         variable contents against 0; 0 indicates success, all other
  816.         values are error codes as defined by dos.library.
  817.  
  818.    RESULT
  819.     icon -- Pointer to a struct DiskObject or NULL in case of error.
  820.         You can use IoErr() to retrieve the error code or use the
  821.         ICONA_ErrorCode tag instead.
  822.  
  823.    EXAMPLE
  824.  
  825.     /* Retrieve the default drawer icon. */
  826.     struct DiskObject *icon;
  827.     LONG errorCode;
  828.  
  829.     icon = GetIconTags(NULL,
  830.         ICONGETA_GetDefaultType,WBDRAWER,
  831.         ICONA_ErrorCode,&errorCode,
  832.     TAG_DONE);
  833.  
  834.     if(icon == NULL)
  835.     {
  836.         Printf("could not retrieve default drawer icon;\n");
  837.         PrintFault(errorCode,NULL);
  838.     }
  839.  
  840.     /* Retrieve the default "picture" icon. */
  841.     icon = GetIconTags(NULL,
  842.         ICONGETA_GetDefaultName,"picture",
  843.     TAG_DONE);
  844.  
  845.     /* Retrieve the default "picture" icon; if there is no
  846.      * such default icon, retrieve the default project
  847.      * icon instead.
  848.      */
  849.     icon = GetIconTags(NULL,
  850.         ICONGETA_GetDefaultName,"picture",
  851.         ICONGETA_GetDefaultType,WBPROJECT,
  852.     TAG_DONE);
  853.  
  854.     /* Retrieve the regular, non-palette-mapped version of
  855.      * an icon.
  856.      */
  857.     icon = GetIconTags("file",
  858.         ICONGETA_GetPaletteMappedIcon,FALSE,
  859.     TAG_DONE);
  860.  
  861.     /* Retrieve the icon for a file; if there is no icon associated
  862.      * with it, retrieve a default icon that matches the file.
  863.      * Also, remember whether we got a real icon or a fake one.
  864.      */
  865.     LONG isFakeIcon;
  866.  
  867.     icon = GetIconTags("file",
  868.         ICONGETA_FailIfUnavailable,FALSE,
  869.         ICONGETA_IsDefaultIcon,&isFakeIcon,
  870.     TAG_DONE);
  871.  
  872.     if(icon != NULL)
  873.     {
  874.         Printf("got an icon at 0x%08lx, and it is a %s icon.\n",
  875.             icon,isFakeIcon ? "fake" : "real");
  876.     }
  877.  
  878.    NOTES
  879.     This function is a superset of GetDefDiskObject(), GetDiskObject()
  880.     and GetDiskObjectNew().
  881.  
  882.     If a palette-mapped icon is set to allocate its colours from the
  883.     default screen, such as the Workbench screen, icon.library may
  884.     resort to remap its colours in the course of Workbench screen
  885.     close/reopen transitions. This means that you cannot depend upon
  886.     the icon's image bitmaps to stay the same size, shape or colour.
  887.     If this is what you need, you should either create your own images
  888.     from the palette mapped data or make copies of the icon image
  889.     bitmaps and the associated colour table.
  890.  
  891.     If during Workbench close/open transitions the global remap
  892.     screen becomes NULL, GetIconTagList() may refuse to return a
  893.     remapped icon and return with an error (ERROR_REQUIRED_ARG_MISSING)
  894.     instead.
  895.  
  896.    SEE ALSO
  897.     workbench/icon.h
  898.     workbench/workbench.h
  899.     icon.library/GetDiskObject
  900.     icon.library/GetDiskObjectNew
  901.     icon.library/GetDefDiskObject
  902.     icon.library/IconControlA
  903.     icon.library/PutIconTagList
  904.  
  905. icon.library/IconControlA                           icon.library/IconControlA
  906.  
  907.    NAME
  908.     IconControlA -- Set and get icon and icon.library options (V44)
  909.  
  910.    SYNOPSIS
  911.     processed = IconControlA(icon,tags);
  912.     D0                       A0   A1
  913.  
  914.     ULONG IconControlA(struct DiskObject *,struct TagItem *);
  915.  
  916.     processed = IconControl(icon,tag1,...);
  917.  
  918.     ULONG IconControl(struct DiskObject *,Tag tag1,...);
  919.  
  920.    FUNCTION
  921.  
  922.     This function is used to modify and query icon and icon.library
  923.     options.
  924.  
  925.    INPUTS
  926.     icon -- Pointer to a struct DiskObject, or NULL if global
  927.         options are to be modified/queried.
  928.     tags -- Options to modify/query.
  929.  
  930.    TAGS
  931.     ICONCTRLA_SetGlobalScreen (struct Screen *) -- Pointer to the
  932.         screen to remap palette mapped icons to. This is commonly
  933.         used by workbench.library after it has initialized itself
  934.         and before/after screen open/close transitions. If the
  935.         screen is set to NULL, the icon colour remapping strategy is
  936.         changed: colours are no longer allocated from a screen
  937.         and the colours to map to will come from a default colour
  938.         colour table with four palette entries. Please note that
  939.         once you select a screen to remap to, you cannot tell
  940.         icon.library to use a different screen; you first need to
  941.         tell icon.library to "let go" of the previously selected
  942.         screen by passing a NULL ICONCTRLA_SetGlobalScreen parameter.
  943.         You can set a different screen only after this is done.
  944.  
  945.     ICONCTRLA_GetGlobalScreen (struct Screen **) -- Pointer to the
  946.         screen to remap palette mapped icons to.
  947.  
  948.     ICONCTRLA_SetGlobalPrecision (LONG) -- Set the global colour
  949.         allocation precision used when remapping icons for
  950.         display. Default is PRECISION_ICON.
  951.  
  952.     OBP_Precision (LONG) -- Can be used as an alias for the
  953.         ICONCTRLA_SetGlobalPrecision tag.
  954.  
  955.     ICONCTRLA_GetGlobalPrecision (LONG *) -- Get the global colour
  956.         allocation precision used when remapping icons for
  957.         display.
  958.  
  959.     ICONCTRLA_SetGlobalEmbossRect (struct Rectangle *) -- Set the
  960.         frame sizes used for drawing icons. The Rectangle
  961.         must be initialized as follows:
  962.  
  963.             Rectangle->MinX  Width of left edge border (negative),
  964.                              must be in the range [-255..-1]
  965.             Rectangle->MinY  Height of top edge border (negative),
  966.                              must be in the range [-255..-1]
  967.             Rectangle->MaxX  Width of right edge border (positive),
  968.                              must be in the range [1..255]
  969.             Rectangle->MaxY  Height of bottom edge border (positive),
  970.                              must be in the range [1..255]
  971.  
  972.     ICONCTRLA_GetGlobalEmbossRect (struct Rectangle *) -- Get the
  973.         frame sizes used for drawing icons.
  974.  
  975.     ICONCTRLA_SetGlobalFrameless (BOOL) -- Select whether icons
  976.         should always be drawn without a surrounding frame.
  977.         This option defaults to FALSE.
  978.  
  979.     ICONCTRLA_GetGlobalFrameless (LONG *) -- Query whether icons
  980.         are always drawn without a surrounding frame.
  981.  
  982.     ICONCTRLA_SetGlobalIdentifyHook (struct Hook *) -- Set the
  983.         hook that is invoked when trying to find an icon
  984.         for a file/drawer/volume that does not have an
  985.         icon associated with it. If set to NULL, no hook
  986.         will be called. The hook will be called with the
  987.         following parameters:
  988.  
  989.         hookFunc(hook,reserved,iim)
  990.                   A0     A2    A1
  991.  
  992.         VOID hookFunc(struct Hook *hook,APTR reserved,
  993.                       struct IconIdentifyMsg *iim);
  994.  
  995.         The reserved parameter will be set to NULL (V44).
  996.  
  997.         The icon identification message contents are as follows:
  998.  
  999.             iim_SysBase
  1000.             iim_DOSBase
  1001.             iim_UtilityBase
  1002.             iim_IconBase
  1003.                 Library base pointers set up for your use.
  1004.  
  1005.             iim_FileLock
  1006.                 A lock on the object to return an icon for.
  1007.                 This lock is guaranteed to be non-NULL.
  1008.  
  1009.             iim_ParentLock
  1010.                 A lock on the object's parent directory. This
  1011.                 may be NULL if iim_FileLock points to a volume's
  1012.                 root directory. In such a case you should return
  1013.                 a WBDISK type icon instead of a WBDRAWER icon.
  1014.  
  1015.             iim_FIB
  1016.                 An initialized FileInfoBlock structure; prior
  1017.                 to passing iim_FIB to you, Examine(iim_FileLock,iim_FIB)
  1018.                 was called. Unlike the other members of this data
  1019.                 structure, you may modify the contents of iim_FIB.
  1020.  
  1021.             iim_FileHandle
  1022.                 If the object to return an icon for is a file,
  1023.                 this member will contain a file handle that can
  1024.                 be used to Read() its contents. The file read
  1025.                 position will be set to the beginning of
  1026.                 the file. Note that this member can be NULL.
  1027.  
  1028.             iim_Tags
  1029.                 A copy of the tag item list passed to GetIconTagList();
  1030.                 if you are going to call GetIconTagList() in your
  1031.                 hook, be sure to include this list as part of the
  1032.                 tag list you pass to it.
  1033.  
  1034.                 NOTE: This list does not include the tag
  1035.                       ICONA_FailIfUnavailable. Keep in mind that
  1036.                       the use of this tag can trigger a recursion
  1037.                       if the icon you tried to retrieve via
  1038.                       GetIconTagList() does not exist: your hook
  1039.                       code will be invoked again.
  1040.  
  1041.         With the exception of iim_FIB, all members of the
  1042.         IconIdentifyMsg are read-only; you may pass them to
  1043.         functions like Read(), Examine(), etc. but you
  1044.         may not Close() files, UnLock() locks or perform
  1045.         other functions that may result in the data structures
  1046.         getting deallocated or trashed.
  1047.  
  1048.         When you manage to find the right icon type for the object
  1049.         to be examined, you should return a pointer to a
  1050.         struct DiskObject that can be freed using FreeDiskObject()
  1051.         lateron. Note that you cannot just return a pointer to a
  1052.         statically initialized data structure in your code, you
  1053.         must return a pointer to a DiskObject allocated by icon.library
  1054.         itself, such as through GetIconTagList(), DupDiskObjectA()
  1055.         or NewDiskObject().
  1056.  
  1057.         The icon you return will be checked to make sure that its
  1058.         type matches the corresponding object. For example, returning
  1059.         a WBDRAWER icon for a volume root directory will cause that
  1060.         icon to be released and to be ignored.
  1061.  
  1062.     ICONCTRLA_GetGlobalIdentifyHook (struct Hook **) -- Get the
  1063.         hook that is invoked when trying to find an icon
  1064.         for a file/drawer/volume that does not have an
  1065.         icon associated with it.
  1066.  
  1067.     ICONCTRLA_SetGlobalMaxNameLength (LONG) -- icon.library has
  1068.         a built-in file name length limit that affects whether
  1069.         icon files are read and written. Currently, the default
  1070.         for this value is 25 characters. This is sufficient for
  1071.         an icon file name acceptable with the ROM filing system.
  1072.         This limit has two effects: if an icon file is to be
  1073.         written whose name would be longer than the limit,
  1074.         icon.library will silently abort the write attempt and
  1075.         pretend that the icon file has been written; this is done
  1076.         in order to avoid overwriting the original data file with
  1077.         the icon file. If an icon file was read that turns out to
  1078.         contain invalid icon data, another test is done in order to
  1079.         find out whether the file name was longer than the limit. If
  1080.         this is the case, it is assumed that the data was read from
  1081.         the original file rather than from the icon file. The library
  1082.         then pretends that the icon file was not found.
  1083.  
  1084.         This tag can be used to set this length limit. The limit
  1085.         must be in the range [8..255].
  1086.  
  1087.     ICONCTRLA_GetGlobalMaxNameLength (LONG *) -- Retrieve the
  1088.         file name length limit used by icon.library.
  1089.  
  1090.     ICONCTRLA_SetGlobalNewIconsSupport (BOOL) -- Select whether
  1091.         icon.libray should read and return coloured icon images stored
  1092.         in NewIcons format.
  1093.         This option defaults to TRUE.
  1094.  
  1095.     ICONCTRLA_GetGlobalNewIconsSupport (LONG *) -- Query whether
  1096.         icon.library will read and return coloured icon images
  1097.         stored in NewIcons format.
  1098.  
  1099.     ICONCTRLA_SetGlobalColorIconSupport (BOOL) -- Select whether
  1100.         icon.libray should read and return coloured icon images.
  1101.         This option defaults to TRUE.
  1102.  
  1103.     ICONCTRLA_GetGlobalColorIconSupport (LONG *) -- Query whether
  1104.         icon.library will read and return coloured icon images.
  1105.  
  1106.     ICONA_ErrorCode (LONG *) -- Pointer to a LONG word variable to
  1107.         store error codes in. Note that this variable will be
  1108.         initialized regardless of whether an error occured or not.
  1109.         Thus, you can check for an error condition by comparing the
  1110.         variable contents against 0; 0 indicates success, all other
  1111.         values are error codes as defined by dos.library.
  1112.  
  1113.     ICONA_ErrorTagItem (struct TagItem **) -- When an error occurs
  1114.         whilst processing the tag item list passed to IconControl(),
  1115.         you can have a pointer to the item that caused the error
  1116.         passed back via the ICONA_ErrorTagItem tag. Note that for
  1117.         TagItem lists allocated from the stack the address passed
  1118.         back to you may no longer be valid when control returns from
  1119.         IconControl().
  1120.  
  1121.     The following tags need a valid icon parameter to operate on.
  1122.     If the parameter is missing or invalid, it will be registered
  1123.     as an error.
  1124.  
  1125.     ICONCTRLA_GetImageMask1 (PLANEPTR *) -- Pointer to the mask plane
  1126.         for the regular icon image (icon->do_Gadget.GadgetRender).
  1127.         Note that this may be NULL.
  1128.  
  1129.     ICONCTRLA_GetImageMask2 (PLANEPTR *) -- Pointer to the mask plane
  1130.         for the alternate icon image (icon->do_Gadget.SelectRender).
  1131.         Note that this may be NULL.
  1132.  
  1133.     ICONCTRLA_SetTransparentColor1 (LONG) -- Set the transparent
  1134.         colour for a palette mapped icon image, in this case the
  1135.         regular icon image (icon->do_Gadget.GadgetRender). The
  1136.         colour must be among the valid palette entries, e.g. for
  1137.         a 16 colour image, the transparent colour may not be
  1138.         larger than 15. To make the icon image opaque, set its
  1139.         transparent colour to -1.
  1140.  
  1141.     ICONCTRLA_GetTransparentColor1 (LONG *) -- Get the transparent
  1142.         colour for a palette mapped icon image, in this case the
  1143.         regular icon image (icon->do_Gadget.GadgetRender). If
  1144.         the image is opaque, its "transparent colour" will be
  1145.         returned as -1. Note that this data is valid only for
  1146.         palette mapped icons; for other types, you may not
  1147.         receive any meaningful result.
  1148.  
  1149.     ICONCTRLA_SetTransparentColor2 (LONG) -- Set the transparent
  1150.         colour for a palette mapped icon image, in this case the
  1151.         alternate icon image (icon->do_Gadget.SelectRender). The
  1152.         colour must be among the valid palette entries, e.g. for
  1153.         a 16 colour image, the transparent colour may not be
  1154.         larger than 15. To make the icon image opaque, set its
  1155.         transparent colour to -1. Please note that you can set
  1156.         the alternate image transparent colour only if there is
  1157.         an alternate image.
  1158.  
  1159.     ICONCTRLA_GetTransparentColor2 (LONG *) -- Get the transparent
  1160.         colour for a palette mapped icon image, in this case the
  1161.         alternate icon image (icon->do_Gadget.SelectRender). If
  1162.         the image is opaque, its "transparent colour" will be
  1163.         returned as -1. Note that this data is valid only for
  1164.         palette mapped icons; for other types, you may not
  1165.         receive any meaningful result. Likewise, if there is
  1166.         no alternate image, no information may be available.
  1167.  
  1168.     ICONCTRLA_SetPalette1 (struct ColorRegister *) -- Set the colour
  1169.         palette for a palette mapped icon image, in this case the
  1170.         regular icon image (icon->do_Gadget.GadgetRender).
  1171.  
  1172.     ICONCTRLA_GetPalette1 (struct ColorRegister **) -- Get the colour
  1173.         palette for a palette mapped icon image, in this case the
  1174.         regular icon image (icon->do_Gadget.GadgetRender). Note
  1175.         that this data is valid only for palette mapped icons; for
  1176.         other types, you may not receive any meaningful result.
  1177.         Note that the number of palette entries in this table
  1178.         matches the number of colours in use when the icon
  1179.         was first created.
  1180.  
  1181.     ICONCTRLA_SetPalette2 (struct ColorRegister *) -- Set the colour
  1182.         palette for a palette mapped icon image, in this case the
  1183.         alternate icon image (icon->do_Gadget.SelectRender).
  1184.  
  1185.     ICONCTRLA_GetPalette2 (struct ColorRegister **) -- Get the colour
  1186.         palette for a palette mapped icon image, in this case the
  1187.         alternate icon image (icon->do_Gadget.SelectRender). Note
  1188.         that this data is valid only for palette mapped icons; for
  1189.         other types, you may not receive any meaningful result.
  1190.         If there is no alternate image, no information may be
  1191.         available.
  1192.         Note that the number of palette entries in this table
  1193.         matches the number of colours in use when the icon
  1194.         was first created.
  1195.  
  1196.     ICONCTRLA_SetPaletteSize1 (ULONG) -- Set the size of the colour
  1197.         palette to be used for a palette mapped icon image, in
  1198.         this case the regular icon image (icon->do_Gadget.GadgetRender).
  1199.         This value must be in the range [1..256].
  1200.  
  1201.     ICONCTRLA_GetPaletteSize1 (ULONG *) -- Get the size of the colour
  1202.         palette to be used for a palette mapped icon image, in
  1203.         this case the regular icon image (icon->do_Gadget.GadgetRender).
  1204.         Note that this data is valid only for palette mapped icons; for
  1205.         other types, you may not receive any meaningful result.
  1206.  
  1207.     ICONCTRLA_SetPaletteSize2 (ULONG) -- Set the size of the colour
  1208.         palette to be used for a palette mapped icon image, in
  1209.         this case the alternate icon image (icon->do_Gadget.SelectRender).
  1210.         This value must be in the range [1..256].
  1211.  
  1212.     ICONCTRLA_GetPaletteSize2 (ULONG *) -- Get the size of the colour
  1213.         palette to be used for a palette mapped icon image, in
  1214.         this case the alternate icon image (icon->do_Gadget.SelectRender).
  1215.         Note that this data is valid only for palette mapped icons; for
  1216.         other types, you may not receive any meaningful result.
  1217.         If there is no alternate image, no information may be
  1218.         available.
  1219.  
  1220.     ICONCTRLA_SetImageData1 (UBYTE *) -- Set the image data to be used for
  1221.         a palette mapped icon image, in this case the regular icon
  1222.         image (icon->do_Gadget.GadgetRender). There must be exactly
  1223.         as many bytes of image data as the image width multiplied
  1224.         by its height requires.
  1225.  
  1226.         To drop the palette mapped image data associated with an icon,
  1227.         use "ICONCTRLA_SetImageData1,NULL,".
  1228.  
  1229.     ICONCTRLA_GetImageData1 (UBYTE **) -- Get the image data to be used for
  1230.         a palette mapped icon image, in this case the regular icon
  1231.         image (icon->do_Gadget.GadgetRender). Note that this data is
  1232.         valid only for palette mapped icons; for other types, you may
  1233.         not receive any meaningful result.
  1234.  
  1235.     ICONCTRLA_SetImageData2 (UBYTE *) -- Set the image data to be used for
  1236.         a palette mapped icon image, in this case the alternate icon
  1237.         image (icon->do_Gadget.SelectRender). There must be exactly
  1238.         as many bytes of image data as the image width multiplied
  1239.         by its height requires.
  1240.  
  1241.         To drop the palette mapped image data associated with the alternate
  1242.         image of an icon, use "ICONCTRLA_SetImageData2,NULL,".
  1243.  
  1244.     ICONCTRLA_GetImageData2 (UBYTE **) -- Get the image data to be used for
  1245.         a palette mapped icon image, in this case the alternate icon
  1246.         image (icon->do_Gadget.SelectRender). Note that this data is
  1247.         valid only for palette mapped icons; for other types, you may
  1248.         not receive any meaningful result. If there is no alternate
  1249.         image, no information may be available.
  1250.  
  1251.     ICONCTRLA_SetFrameless (BOOL) -- Select whether the icon should be
  1252.         drawn without a frame. This option defaults to FALSE.
  1253.  
  1254.     ICONCTRLA_GetFrameless (LONG *) -- Query whether the icon should be
  1255.         drawn without a frame.
  1256.  
  1257.     ICONCTRLA_SetNewIconsSupport (BOOL) -- Select whether palette mapped
  1258.         icon images that were originally stored in NewIcons format
  1259.         should be written back in the same format. This option
  1260.         defaults to TRUE.
  1261.  
  1262.     ICONCTRLA_GetNewIconsSupport (LONG *) -- Query whether palette mapped
  1263.         icon images that were originally stored in NewIcons format
  1264.         should be written back in the same format.
  1265.  
  1266.     ICONCTRLA_SetAspectRatio (UBYTE) -- Set the icon aspect ratio; this
  1267.         consists of a numerator and a denominator packed into a
  1268.         single byte (the PACK_ICON_ASPECT_RATIO() macro can be used
  1269.         for encoding this parameter). If the icon aspect ratio is
  1270.         unknown, ICON_ASPECT_RATIO_UNKNOWN should be used.
  1271.  
  1272.     ICONCTRLA_GetAspectRatio (UBYTE *) -- Get the icon aspect ratio; this
  1273.         consists of a numerator and a denominator packed into a
  1274.         single byte (the UNPACK_ICON_ASPECT_RATIO() macro can be used
  1275.         for decoding this value). If the icon aspect ratio is unknown,
  1276.         ICON_ASPECT_RATIO_UNKNOWN will be returned.
  1277.  
  1278.     ICONCTRLA_SetWidth (ULONG) -- Select the palette mapped icon image
  1279.         width. This value must be in the range [1..256].
  1280.  
  1281.     ICONCTRLA_GetWidth (ULONG *) -- Query the palette mapped icon image
  1282.         width. Note that this data is valid only for palette mapped icons;
  1283.         for other types, you may not receive any meaningful result.
  1284.  
  1285.     ICONCTRLA_SetHeight (ULONG) -- Select the palette mapped icon image
  1286.         height. This value must be in the range [1..256].
  1287.  
  1288.     ICONCTRLA_GetHeight (ULONG *) -- Query the palette mapped icon image
  1289.         height. Note that this data is valid only for palette mapped icons;
  1290.         for other types, you may not receive any meaningful result.
  1291.  
  1292.     ICONCTRLA_IsPaletteMapped (LONG *) -- Query whether the icon is using
  1293.         palette mapped icon images.
  1294.  
  1295.     ICONCTRLA_IsNewIcon (LONG *) -- Query whether the icon is of the
  1296.         NewIcon type.
  1297.  
  1298.     ICONCTRLA_IsNativeIcon (LONG *) -- There is an important difference
  1299.         between struct DiskObject icons allocated by icon.library itself
  1300.         (these are the so-called "native" icons) and statically initialized
  1301.         icons which consist solely of a simple struct DiskObject which may
  1302.         be part of a program's static data area. For example, you can
  1303.         attach a palette mapped icon image to a "native" icon, which is
  1304.         something you cannot do with a statically allocated icon. To help
  1305.         you tell the two types apart, you can use the ICONCTRLA_IsNativeIcon
  1306.         query tag.
  1307.  
  1308.     ICONGETA_IsDefaultIcon (LONG *) -- Query whether this icon is associated
  1309.         with a file/drawer/volume or is a "fake" icon that was constructed
  1310.         for an object that has no icon associated with it.
  1311.  
  1312.     ICONCTRLA_GetScreen (struct Screen **) -- Get the screen this icon
  1313.         has been remapped to and whose colour map it uses. Note that this
  1314.         data is valid only for palette mapped icons; for other types, you
  1315.         may not receive any meaningful result.
  1316.  
  1317.         This tag may return NULL if the icon is not currently associated
  1318.         with a screen.
  1319.  
  1320.     ICONCTRLA_HasRealImage2 (LONG *) -- icon.library may generate an
  1321.         alternate image for palette mapped icons if there is no image
  1322.         data stored for this image. To find out whether an icon
  1323.         was generated or is part of the original icon image, use the
  1324.         ICONCTRLA_HasRealImage2 tag.
  1325.  
  1326.    RESULT
  1327.     processed -- Number of tags that were processed correctly, i.e.
  1328.         the number of tags whose parameters are in order, for which
  1329.         information could be returned, etc. If processing stops because of
  1330.         an error, the number returned by this function will be smaller
  1331.         than the number of tag items passed in. The same happens if
  1332.         the information you wanted to obtain is unavailable. In any
  1333.         case, check the error code this routine can set up for you.
  1334.  
  1335.    EXAMPLE
  1336.     /* Check if the icon is palette mapped. */
  1337.     LONG isPaletteMapped;
  1338.     LONG errorCode;
  1339.     struct DiskObject *icon;
  1340.  
  1341.     if(IconControl(icon,
  1342.         ICONCTRLA_IsPaletteMapped,&isPaletteMapped,
  1343.         ICONA_ErrorCode,&errorCode,
  1344.     TAG_DONE) == 1)
  1345.     {
  1346.         Printf("the icon %s palette mapped\n",
  1347.             isPaletteMapped ? "is" : "is not");
  1348.     }
  1349.     else
  1350.     {
  1351.         Printf("could not query icon information;\n");
  1352.         PrintFault(errorCode,NULL);
  1353.     }
  1354.  
  1355.     /* Set the icon colour remapping precision. */
  1356.     IconControl(NULL,
  1357.         ICONCTRLA_SetGlobalPrecision,PRECISION_EXACT,
  1358.     TAG_DONE);
  1359.  
  1360.     /* Query the embossing rectangle dimensions and
  1361.      * the identification hook.
  1362.      */
  1363.     struct Rectangle rect;
  1364.     struct Hook *hook;
  1365.  
  1366.     if(IconControl(NULL,
  1367.         ICONCTRLA_GetGlobalEmbossRect,&rect,
  1368.         ICONCTRLA_GetGlobalIdentifyHook,&hook,
  1369.     TAG_DONE) == 2)
  1370.     {
  1371.         Printf("embossing rect: %ld,%ld,%ld,%ld\n",
  1372.             rect.MinX,rect.MaxX,rect.MinY,rect.MaxY);
  1373.         Printf("identification hook: 0x%08lx\n",
  1374.             hook);
  1375.     }
  1376.  
  1377.    NOTES
  1378.     Changing an icon's palette or image data does not automatically
  1379.     produce a different icon image you can use. To do this, you
  1380.     must re-layout it using LayoutIcon().
  1381.  
  1382.     When querying parameters, make sure to always pass in a pointer
  1383.     to a LONG word variable to store the result in.
  1384.  
  1385.     Some get/set operations may cause additional memory to be
  1386.     allocated. This may fail; be prepared.
  1387.  
  1388.     IconControl() processes the tag item list in sequential order.
  1389.     This has consequences for several tags, such as the palette size
  1390.     and the transparent colour. For example, if you want to make
  1391.     colour #14 of an icon image transparent, make sure to have the
  1392.     palette size set to at least 15 colours before you try to change
  1393.     the transparent colour. Otherwise, IconControl() may refuse to
  1394.     set the transparent colour to #14 since it won't know that there
  1395.     should be more than 14 colours in that image at the time you try
  1396.     to set it. Therefore, if you wanted to change the palette size and
  1397.     the transparent colour in the same tag item list, make sure that the
  1398.     palette size change tag appears before the transparent colour change
  1399.     tag.
  1400.  
  1401.     As described above, some of the operations on icons are not
  1402.     supported for DiskObjects not allocated through icon.library. In
  1403.     such cases you will receive an error code ERROR_ACTION_NOT_KNOWN.
  1404.  
  1405.    SEE ALSO
  1406.     dos.library/IoErr
  1407.     icon.library/DupDiskObjectA
  1408.     icon.library/GetIconTagList
  1409.     icon.library/LayoutIcon
  1410.     icon.library/NewDiskObject
  1411.     graphics.library/BltMaskBitMapRastPort
  1412.     graphics.library/ObtainBestPenA
  1413.     utility.library/CallHookPkt
  1414.     graphics/view.h
  1415.     workbench/icon.h
  1416.     workbench/workbench.h
  1417.  
  1418. icon.library/LayoutIconA                             icon.library/LayoutIconA
  1419.  
  1420.    NAME
  1421.     LayoutIconA -- Adapt a palette-mapped icon for display (V44)
  1422.  
  1423.    SYNOPSIS
  1424.     success = LayoutIconA(icon,screen,tags);
  1425.     D0                    A0   A1     A2
  1426.  
  1427.     BOOL LayoutIconA(struct DiskObject *icon,struct Screen *screen,
  1428.                      struct TagItem *tags);
  1429.  
  1430.     success = LayoutIcon(icon,screen,...);
  1431.  
  1432.     BOOL LayoutIcon(struct DiskObject *icon,struct Screen *screen,...);
  1433.  
  1434.    FUNCTION
  1435.     This function will prepare an icon for display, either on a
  1436.     specific screen or using a default colour palette. It is
  1437.     useful only for palette mapped icons.
  1438.  
  1439.    INPUTS
  1440.     icon -- The icon to be remapped. This must be a palette mapped
  1441.         icon.
  1442.     screen -- Pointer to a screen to remap the icon for or NULL
  1443.         to remap the icon to use the system default colour palette
  1444.         or something very similar to it (this means: four colours
  1445.         only).
  1446.     tags -- Additional rendering options.
  1447.  
  1448.    TAGS
  1449.     OBP_Precision (LONG) -- Pen colour allocation precision.
  1450.         Default is the same precision as set in the global
  1451.         icon.library settings (see IconControlA()).
  1452.  
  1453.    OUTPUTS
  1454.     success -- TRUE if the icon could be remapped, FALSE if
  1455.         the remapping failed for some reason. In case of
  1456.         of failure, icon.library will try its best to keep
  1457.         the icon in a presentable state, but this may fail.
  1458.         In case of failure, the error code can be retrieved
  1459.         using dos.library/IoErr.
  1460.  
  1461.    NOTES
  1462.     You must make sure that the screen you remap to does not
  1463.     go away while there is an icon to use its colours. For
  1464.     a public screen, the easiest way to guarantee this is
  1465.     to keep it locked (see intuition.library/LockPubScreen).
  1466.     For custom screens, just don't close them! If you have to close
  1467.     the screen or need to keep your icon around until after a screen
  1468.     is closed, you should call LayoutIcon() with a NULL screen
  1469.     parameter. This will release all pens the icon has allocated
  1470.     and remap the icon to a default set of colours. Alternatively,
  1471.     you can dispose of the icon via FreeDiskObject() which
  1472.     will also release all pens the icon has allocated, including
  1473.     the icon itself, of course.
  1474.  
  1475.     Icons remapped to the global default screen (normally, that
  1476.     would be the Workbench screen) may get changed and remapped
  1477.     again during Workbench close/open transitions. To prevent
  1478.     this from taking place, just make sure that the Workbench
  1479.     screen does not close (e.g. via LockPubScreen("Workbench")).
  1480.  
  1481.    SEE ALSO
  1482.     dos.library/IoErr
  1483.     graphics.library/ObtainBestPenA
  1484.     graphics.library/ReleasePen
  1485.     icon.library/FreeDiskObject
  1486.     icon.library/GetIconTagList
  1487.     icon.library/IconControl
  1488.     intuition.library/LockPubScreen
  1489.     intuition.library/UnlockPubScreen
  1490.     graphics/view.h
  1491.  
  1492. icon.library/MatchToolValue                       icon.library/MatchToolValue
  1493.  
  1494.    NAME
  1495.     MatchToolValue - check a tool type variable for a particular value.
  1496.  
  1497.    SYNOPSIS
  1498.     result = MatchToolValue(typeString, value)
  1499.       D0                        A0        A1
  1500.  
  1501.     BOOL MatchToolValue(STRPTR, STRPTR);
  1502.  
  1503.    FUNCTION
  1504.     MatchToolValue is useful for parsing a tool type value for
  1505.     a known value.  It knows how to parse the syntax for a tool
  1506.     type value (in particular, it knows that '|' separates
  1507.     alternate values).  Note that the parsing is case insensitive.
  1508.  
  1509.    INPUTS
  1510.     typeString -- a ToolType value (as returned by FindToolType)
  1511.     value -- you are interested if value appears in typeString
  1512.  
  1513.    RESULTS
  1514.     result -- TRUE if the value was in typeString else FALSE.
  1515.  
  1516.    EXAMPLE
  1517.     Assume there are two type strings:
  1518.         type1 = "text"
  1519.         type2 = "a|b|c"
  1520.  
  1521.     MatchToolValue( type1, "text" ) returns TRUE
  1522.     MatchToolValue( type1, "TEXT" ) returns TRUE
  1523.     MatchToolValue( type1, "data" ) returns FALSE
  1524.     MatchToolValue( type2, "a" )    returns TRUE
  1525.     MatchToolValue( type2, "b" )    returns TRUE
  1526.     MatchToolValue( type2, "d" )    returns FALSE
  1527.     MatchToolValue( type2, "a|b" )  returns FALSE
  1528.  
  1529.    NOTES
  1530.     icon.library V44 skips blank spaces surrounding the typeString
  1531.     options and the value string. Older icon.library versions did
  1532.     not support this.
  1533.  
  1534.    SEE ALSO
  1535.     icon.library/FindToolType
  1536.     utility.library/Stricmp
  1537.  
  1538. icon.library/NewDiskObject                         icon.library/NewDiskObject
  1539.  
  1540.    NAME
  1541.     NewDiskObject -- Create an empty icon (V44)
  1542.  
  1543.    SYNOPSIS
  1544.     icon = NewDiskObject(type)
  1545.     D0                   D0
  1546.  
  1547.     struct DiskObject * NewDiskObject(LONG type);
  1548.  
  1549.    FUNCTION
  1550.     This function is used to create an "empty" DiskObject
  1551.     structure, which has no image data associated with it.
  1552.     Still, all the necessary structures are in place,
  1553.     you just have to fill them in.
  1554.  
  1555.    INPUTS
  1556.     type -- Icon type to create, this must be one of WBDISK,
  1557.         WBDRAWER, WBTOOL, WBPROJECT, WBGARBAGE, WBDEVICE or WBKICK.
  1558.  
  1559.    RESULT
  1560.     icon -- Pointer to a struct DiskObject or NULL in case of error.
  1561.         You can use IoErr() to retrieve the error code.
  1562.  
  1563.    NOTES
  1564.     The DiskObject returned by this function will have a zero
  1565.     width and height Image in the do_Gadget.GadgetRender member
  1566.     and the do_Gadget.Width/do_Gadget.Height members will both
  1567.     be 0, too.
  1568.  
  1569.    SEE ALSO
  1570.     dos.library/IoErr
  1571.     workbench/icon.h
  1572.     workbench/workbench.h
  1573.  
  1574. icon.library/PutDefDiskObject                   icon.library/PutDefDiskObject
  1575.  
  1576.    NAME
  1577.     PutDefDiskObject - write disk object as the default for its type.  (V36)
  1578.  
  1579.    SYNOPSIS
  1580.     status = PutDefDiskObject(diskobj)
  1581.       D0                        A0
  1582.  
  1583.     BOOL PutDefDiskObject(struct DiskObject *);
  1584.  
  1585.    FUNCTION
  1586.     This routine writes out a DiskObject structure, and its
  1587.     associated information.  If the call fails, FALSE will
  1588.     be returned.  The reason for the failure may be obtained
  1589.     via IoErr().
  1590.  
  1591.     Note that this function calls PutDiskObject() internally which means
  1592.     that this call (if sucessful) notifies workbench than an icon has
  1593.     been created/modified.
  1594.  
  1595.     Using this routine protects you from any future changes to
  1596.     the way default icons are stored within the system.
  1597.  
  1598.    INPUTS
  1599.     diskobj -- a pointer to a DiskObject
  1600.  
  1601.    RESULTS
  1602.     status -- TRUE if the call succeeded else FALSE
  1603.  
  1604.    SEE ALSO
  1605.     dos.library/IoErr
  1606.     icon.library/GetDefDiskObject
  1607.     icon.library/GetIconTagList
  1608.     icon.library/PutDiskObject
  1609.  
  1610. icon.library/PutDiskObject                         icon.library/PutDiskObject
  1611.  
  1612.    NAME
  1613.     PutDiskObject - write out a DiskObject to disk.
  1614.  
  1615.    SYNOPSIS
  1616.     status = PutDiskObject(name, diskobj)
  1617.      D0                    A0      A1
  1618.  
  1619.     BOOL PutDiskObject(STRPTR, struct DiskObject *);
  1620.  
  1621.    FUNCTION
  1622.     This routine writes out a DiskObject structure, and its
  1623.     associated information.  The file name of the info
  1624.     file will be the name parameter with ".info" postpended
  1625.     to it.  If the call fails, FALSE will be returned.  The
  1626.     reason for the failure may be obtained via IoErr().
  1627.  
  1628.     As of release V2.0, PutDiskObject() (if successful) notifies Workbench
  1629.     when an icon has been created/modified.
  1630.  
  1631.     Using this routine protects you from any future changes to
  1632.     the way icons are stored within the system.
  1633.  
  1634.    INPUTS
  1635.     name -- name of the object (pointer to a character string)
  1636.     diskobj -- a pointer to a DiskObject
  1637.  
  1638.    RESULTS
  1639.     status -- TRUE if the call succeeded else FALSE
  1640.  
  1641.    NOTES
  1642.     It is recommended that if you wish to copy an icon from one place
  1643.     to another than you use GetDiskObject() and PutDiskObject()
  1644.     and do not copy them directly.
  1645.  
  1646.    SEE ALSO
  1647.     dos.library/IoErr
  1648.     icon.library/DeleteDiskObject
  1649.     icon.library/FreeDiskObject
  1650.     icon.library/GetDiskObject
  1651.     icon.library/GetIconTagList
  1652.     icon.library/PutIconTagList
  1653.  
  1654. icon.library/PutIconTagList                       icon.library/PutIconTagList
  1655.  
  1656.    NAME
  1657.     PutIconTagList -- Store an icon (V44)
  1658.  
  1659.    SYNOPSIS
  1660.     success = PutIconTagList(name,icon,tags);
  1661.     D0                       A0   A1   A2
  1662.  
  1663.     BOOL PutIconTagList(STRPTR name,struct DiskObject *icon,
  1664.                         struct TagItem *tags);
  1665.  
  1666.     success = PutIconTags(name,icon,tag1,...);
  1667.  
  1668.     BOOL PutIconTags(STRPTR name,struct DiskObject *icon,
  1669.                         Tag tag1,...);
  1670.  
  1671.    FUNCTION
  1672.     This function is used to store an icon; the icon can
  1673.     belong to a file/drawer/volume or it can be a default icon.
  1674.  
  1675.    INPUTS
  1676.     name -- Name of the object the icon is to be stored for,
  1677.         or NULL if a default icon is to be stored.
  1678.     icon -- The icon to be stored.
  1679.     tags -- Storage options.
  1680.  
  1681.    TAGS
  1682.     ICONPUTA_NotifyWorkbench (BOOL) -- Set this to TRUE to notify
  1683.         Workbench of the fact that an icon was changed.
  1684.  
  1685.         This tag defaults to FALSE.
  1686.  
  1687.     ICONPUTA_PutDefaultType (LONG) -- Type of the default icon
  1688.         this icon is to replace; must be one of WBDISK, WBDRAWER,
  1689.         WBTOOL, WBPROJECT, WBGARBAGE, WBDEVICE or WBKICK.
  1690.  
  1691.         If this tag is used, the "name" parameter will be ignored.
  1692.  
  1693.     ICONPUTA_PutDefaultName (STRPTR) -- Name of the default object
  1694.         type this icon is to be stored as.
  1695.  
  1696.         If this tag is used, the "name" parameter will be ignored.
  1697.  
  1698.     ICONPUTA_DropPlanarIconImage (BOOL) -- If you decide that the
  1699.         palette mapped icon imagery is sufficient to represent
  1700.         an icon, you can tell icon.library not to store the original,
  1701.         planar icon image data with the icon file. To do this,
  1702.         set this tag to TRUE. Instead of the planar icon images,
  1703.         a single default image will be stored. This can result
  1704.         in space savings but may not look too pretty.
  1705.  
  1706.         This tag defaults to FALSE.
  1707.  
  1708.     ICONPUTA_DropChunkyIconImage (BOOL) -- This tag can be used to
  1709.         keep the chunky icon image data from getting written
  1710.         to disk.
  1711.  
  1712.         This tag defaults to FALSE.
  1713.  
  1714.     ICONPUTA_DropNewIconToolTypes (BOOL) -- This tag controls whether
  1715.         any NewIcon tool types will be omitted when writing the
  1716.         icon to disk. TRUE will omit the data.
  1717.  
  1718.         This tag defaults to FALSE.
  1719.  
  1720.     ICONPUTA_OptimizeImageSpace (BOOL) -- A palette mapped icon
  1721.         image might not use the entire icon palette. By default,
  1722.         icon.library does not bother about this, it expects the
  1723.         creator of the icon to choose its palette efficiently.
  1724.         But just in case, you can tell icon.library to attempt
  1725.         to identify how many colours are really in use and to
  1726.         optimize its image compressor for them. This may take
  1727.         extra time and is not recommended for daily use.
  1728.  
  1729.         This tag defaults to FALSE.
  1730.  
  1731.     ICONPUTA_OnlyUpdatePosition (BOOL) -- This tag can be used to
  1732.         reduce the overhead in updating icon information on disk
  1733.         if the only information changed is the icon position.
  1734.         For this case, you can set this tag to TRUE. The icon
  1735.         to be modified will have only its do_CurrentX/do_CurrentY
  1736.         member values changed, the remainer will stay unmodified.
  1737.         Please note that this tag only takes effect if the
  1738.         ICONPUTA_PutDefaultType and ICONPUTA_PutDefaultName tags
  1739.         are omitted.
  1740.  
  1741.         This tag defaults to FALSE.
  1742.  
  1743.     ICONPUTA_PreserveOldIconImages (BOOL) -- Before writing a
  1744.         palette mapped icon back to disk, icon.library will make
  1745.         sure that the original planar image data is stored in the
  1746.         file. If you don't want that to happen, set this option to
  1747.         FALSE. This tag will allow you to change the planar icon
  1748.         image data written back to disk.
  1749.  
  1750.         This tag defaults to TRUE.
  1751.  
  1752.     ICONA_ErrorCode (LONG *) -- Pointer to a LONG word variable to
  1753.         store error codes in. Note that this variable will be
  1754.         initialized regardless of whether an error occured or not.
  1755.         Thus, you can check for an error condition by comparing the
  1756.         variable contents against 0; 0 indicates success, all other
  1757.         values are error codes as defined by dos.library.
  1758.  
  1759.    RESULT
  1760.     success -- TRUE if the icon file could be stored, FALSE otherwise.
  1761.         You can use IoErr() to retrieve the error code or use the
  1762.         ICONA_ErrorCode tag instead.
  1763.  
  1764.    EXAMPLE
  1765.     /* Store an icon as the default "picture" icon. */
  1766.     struct DiskObject *icon;
  1767.     LONG errorCode;
  1768.     BOOL success;
  1769.  
  1770.     success = PutIconTags(NULL,icon,
  1771.         ICONPUTA_PutDefaultName,"picture",
  1772.         ICONA_ErrorCode,&errorCode,
  1773.     TAG_DONE);
  1774.  
  1775.     if(success == FALSE)
  1776.     {
  1777.         Printf("could not store default picture icon;\n");
  1778.         PrintFault(errorCode,NULL);
  1779.     }
  1780.  
  1781.    NOTES
  1782.     This function is a superset of PutDefDiskObject() and PutDiskObject().
  1783.  
  1784.     If the name of the icon file to be stored would be too long to fit
  1785.     (as set with IconControl(..., ICONCTRLA_SetGlobalMaxNameLength, ...))
  1786.     then PutIconTagList() will silently pretend that the icon file has
  1787.     been written to disk. However, it will not store the icon file on the
  1788.     disk since there would a risk of accidentally overwriting the file the
  1789.     icon belongs to. If you want to know whether the icon you wrote was
  1790.     in fact written to disk, provide an error code pointer with the
  1791.     ICONA_ErrorCode tag. If the name of the file was too long,
  1792.     PutIconTagList() will still pretend that the icon file was written
  1793.     successfully, but the error code ERROR_TOO_MANY_LEVELS will be stored
  1794.     in the variable you passed in with the ICONA_ErrorCode tag.
  1795.  
  1796.    SEE ALSO
  1797.     workbench/icon.h
  1798.     workbench/workbench.h
  1799.     icon.library/GetIconTagList
  1800.     icon.library/PutDefDiskObject
  1801.     icon.library/PutDiskObject
  1802.  
  1803.